AppleWebSearch Docs

Introduction

AppleWebSearch provides a mechanism for users to make their AppleSearch information sources available to others on the World Wide Web. AppleWebSearch is implemented as a gateway (CGI) application for use with MacHTTP. This means you MUST be running a version of MacHTTP that supports the CGI file type and the "Search Doc" AppleEvent. This means you must use MacHTTP version 1.3.1b1 or later.

AppleWebSearch supports two types of WWW client interfaces. The simplest uses the <isindex> search arguments passed from a WWW client like Mosaic or MacWeb to perform searches on an AppleSearch information source. There is a more comprehensive interface available that uses fill-in forms to collect search arguments from the user. To use the forms interface, you must access MacHTTP and AppleWebSearch using a WWW client capable of supporting forms. MacWeb and the alpha version of Mosaic 2.0 both support forms.

AppleWebSearch is invoked by MacHTTP in response to a client's request for a particular URL. MacHTTP passes arguments to AppleWebSearch via custom AppleEvents. These arguments are obtained from the path and search arguments contained in the URL sent to MacHTTP. If you are unfamiliar with path and search arguments, you may want to read through the documentation and examples that come with the latest beta version of MacHTTP.

AppleWebSearch uses these arguments to perform search operations with the AppleSearch server that it is connected to. The results are formatted into a HTML document that is automatically generated by AppleWebSearch and returned to MacHTTP (and then to the WWW client.) Much of the information in the generated forms can be modified by changing TEXT resources within the AppleWebSearch application.

Installation

To install AppleWebSearch, simply copy the application to the same folder as MacHTTP. If you install AppleWebSearch anywhere else on your system, make sure you place an alias to it in the same folder as MacHTTP, with the same exact name as the original copy of AppleWebSearch.

DO NOT RENAME AppleWebSearch.cgi!!! If you do, it will cease to function correctly. If you absolutely must rename the file, you must modify TEXT resource #150 to reflect the new name.

Your system must have the following software installed for the gateway to function correctly:

AppleWebSearch
MacHTTP 1.3.1b1 or later (and 1.3.1b1 config file or later)
AppleSearch client software
AppleSearch server software (optional, but must be somewhere on your net)
MacTCP
System 7

The AppleSearch server requires a 68040 or better to run.

Starting up AppleWebSearch

You access AppleWebSearch via MacHTTP. AppleWebSearch then accesses the AppleSearch server. Therefore, all the parts must be up and running for everything to work. The start-up sequence usually goes as follows:

Launch the AppleSearch server (unless one is already running elsewhere on your net.)
Launch MacHTTP.
Launch AppleWebSearch.
Connect AppleWebSearch to your AppleSearch server using the "Connect" menu command from AppleWebSearch's File menu.

Accessing the Gateway

Simple Interface

The simple interface to AppleWebSearch will work with any WWW client. To access the gateway, send the following URL from a WWW client to MacHTTP, substituting your host address for the one in the example below:

http://your.host.addr/AppleWebSearch.cgi$SOURCES

This starts the AppleSearching process, presenting the user with a list of active sources available from the AppleSearch server that AppleWebSearch is communicating with. Selecting a server from the list will continue the process, prompting the user for search terms to look for in the selected source. After the user enters the search terms and starts the search, the gateway will return a list of documents that match the search criteria.

Each entry in this list starts with a row of asterisks, indicating the relevence level from 1 to 5, 5 being the best match. The title of the document follows, with the approximate size of the document listed last. Selecting a document from this list causes the gateway to retrieve the document and display it. The gateway is limited to returning 30K chunks of data, so large documents will be divided into multiple parts with a "Click here for more" link at the bottom of the page. This link will cause the next portion of the document to be retrieved.

Forms Interface

The gateway can also be accessed via a forms interface from WWW clients that support HTML forms. The URL to start the query process using the forms interface is:

http://your.host.addr/AppleWebSearch.cgi$FORM

This form attempts to match the user interface provided by the AppleSearch client as shipped by Apple. The different form elements are defined as follows:

Minimum Rank - represents the minimum rank required for a document to be returned. The lower you set this value, the more documents that will be returned. Setting it to "*****" will return only the best matches.
Maximum Returns - defines the maximum number of documents to return in response to a search.
Search For - is a free text field where you enter the keywords to search for. This field is subject to the same restrictions as its counterpart in the AppleSearch client.
Info Source to Search - is a list of sources being served by the AppleSearch server that AppleWebSearch is connected to. You must select on of the sources by clicking on the associated radio button.

Once all data has been entered, click the "Perform Search" button to perform the query. From this point on, the gateway will perform the same as described in the Simple Interface section.

Gateway Arguments

The AppleWebSearch gateway accepts several different commands in the path arguments portion of a URL (the portion of a MacHTTP URL between "$" and "?"). The complete list and any optional arguments follows in BNF notation. An easy way to determine alternate ways to invoke AppleWebSearch is to examine the contents of the current URL being displayed in a WWW client.

FORM - starts the form interface. Takes no arguments.

SOURCES - starts the simple interface. Takes no arguments.

UPDATESOURCES - identical to SOURCES, but it causes AppleWebSearch to request an updated list of sources from the AppleSearch server, rather than using those cached in memory.

The next two commands are very risky to use "stand-alone", mainly because the source number and document number for particular AppleSearch sources and documents may be subject to change if you add new sources, or re-index an existing source. These path arguments are normally generated by the AppleWebSearch application on the fly, in response to user requests.

SEARCH,<source number>[?<keywords>] - If "?<keywords>" is omitted, this generates a page that prompts for search arguments for the AppleSearch source numbered "source number". If search arguments are present ("?<keywords>"), then the entire query is performed, returning the first 40 matches, ranked from best match to worst.

RETRIEVE,<source number>,<doc number>,<chunk size>,<offset> - retrieves the requested number of bytes (chunk size) from the specified document contained in the specified source, starting at the specified offset and continuing until "chunk size" bytes have been returned.

Modifying the Interface

Adventurous souls may wish to modify the AppleWebSearch interface that is presented to WWW clients. All of the HTML text that is returned to clients via MacHTTP is stored in the TEXT resources of the AppleWebSearch.cgi application.

You may modify any of the text contained in these resources to suit your purposes, subject to the following restrictions:

Do not delete or renumber any of the existing TEXT resources
Do not delete any of the %s, %d, %ld, etc. markers in the TEXT resources or change the order of these markers.
Do not change the names of the form elements in the 700 series of resources.

IMPORTANT: AppleWebSearch is limited to passing 512 characters representing search arguments. To increase this limit, you may want to modify the TEXT resource #700 ("Form Header") and change the following line:
<form method=GET action="%s$FORM">
to:
<form method=PUT action="%s$FORM">

Changing "GET" to "PUT" will cause the WWW client to send data to MacHTTP using the PUT method, which will allow up to 2K of search arguments to be passed from MacHTTP to AppleWebSearch.

You may modify the HTML resources, rearrange the form components, and otherwise mutate the TEXT resources. It is STRONGLY recommended that you perform this surgery on a copy of the original application.

Legal Stuff

AppleWebSearch is copyrighted 1994 by the University of Texas-Houston Health Science Center. Portions are copyrighted by Apple Computer, Inc. All rights are reserved by the copyright holders.

AppleWebSearch is being developed by Chuck Shotton of UT-H's Office of Academic Computing. cshotton@oac.hsc.uth.tmc.edu

You are given permission to use this version of AppleWebSearch with any licensed copy of MacHTTP and AppleSearch. This software is being made available from the MacHTTP Home Page and major Macintosh Internet archives and you may not redistribute the software without written permission from the author.